home *** CD-ROM | disk | FTP | other *** search
ggggeeeettttddddaaaatttteeee((((3333CCCC)))) ggggeeeettttddddaaaatttteeee((((3333CCCC)))) NNNNAAAAMMMMEEEE _gggg_eeee_tttt_dddd_aaaa_tttt_eeee - convert user format date and time SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS _####_iiii_nnnn_cccc_llll_uuuu_dddd_eeee _<<<<_tttt_iiii_mmmm_eeee_...._hhhh_>>>> _ssss_tttt_rrrr_uuuu_cccc_tttt _tttt_mmmm _****_gggg_eeee_tttt_dddd_aaaa_tttt_eeee _((((_cccc_oooo_nnnn_ssss_tttt _cccc_hhhh_aaaa_rrrr _****_ssss_tttt_rrrr_iiii_nnnn_gggg_))))_;;;; _eeee_xxxx_tttt_eeee_rrrr_nnnn _iiii_nnnn_tttt _gggg_eeee_tttt_dddd_aaaa_tttt_eeee______eeee_rrrr_rrrr_;;;; DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN _gggg_eeee_tttt_dddd_aaaa_tttt_eeee The _gggg_eeee_tttt_dddd_aaaa_tttt_eeee function converts a string representation of a date or time into a broken-down time. The external variable or macro _gggg_eeee_tttt_dddd_aaaa_tttt_eeee______eeee_rrrr_rrrr is used by _gggg_eeee_tttt_dddd_aaaa_tttt_eeee_((((_)))) to return error values. Templates are used to parse and interpret the input string. The templates are contained in a text file identified by the environment variable _DDDD_AAAA_TTTT_EEEE_MMMM_SSSS_KKKK_.... The DATEMSK variable should be set to indicate the full pathname of the file that contains the templates. The first line in the template that matches the input specification is used for interpretation and conversion into the internal time format. The following field descriptors are supported: _%%%%_%%%% same as _%%%% _%%%%_aaaa abbreviated weekday name _%%%%_AAAA full weekday name _%%%%_bbbb abbreviated month name _%%%%_BBBB full month name _%%%%_cccc locale's appropriate date and time representation _%%%%_CCCC century number (00-99; leading zeros are permitted but not required) _%%%%_dddd day of month (01-31; the leading 0 is optional) _%%%%_DDDD date as %m/%d/%y _%%%%_eeee same as _%%%%d _%%%%_hhhh abbreviated month name _%%%%_HHHH hour (00-23) _%%%%_IIII hour (01-12) PPPPaaaaggggeeee 1111 ggggeeeettttddddaaaatttteeee((((3333CCCC)))) ggggeeeettttddddaaaatttteeee((((3333CCCC)))) _%%%%_mmmm month number (01-12) _%%%%_MMMM minute (00-59) _%%%%_nnnn same as new line _%%%%_pppp locale's equivalent of either AM or PM _%%%%_rrrr The locale's appropriate representation of time in AM and PM notation. In the POSIX locale, this is equivalent to %I:%M:%S %p _%%%%_RRRR time as %H:%M _%%%%_SSSS seconds (00-61). Leap seconds are allowed but are not predictable through use of algorithms. _%%%%_tttt same as tab _%%%%_TTTT time as %H:%M:%S _%%%%_wwww weekday number (Sunday = 0 - 6) _%%%%_xxxx locale's appropriate date representation _%%%%_XXXX locale's appropriate time representation _%%%%_yyyy year within century. When a century is not otherwise specified, values in the range 69-99 refer to years in the twentieth century (1969 to 1999 inclusive); values in the range 00-68 refer to years in the twenty-first century (2000 to 2068 inclusive). _%%%%_YYYY year as ccyy (for example, 1994) _%%%%_ZZZZ time zone name or no characters if no time zone exists. If the time zone supplied by _%%%%_ZZZZ is not the time zone that _gggg_eeee_tttt_dddd_aaaa_tttt_eeee_((((_)))) expects, an invalid input specification error will result. The _gggg_eeee_tttt_dddd_aaaa_tttt_eeee_((((_)))) function calculates an expected time zone based on information supplied to the function (such as the hour, day, and month). The match between the template and input specification performed by _gggg_eeee_tttt_dddd_aaaa_tttt_eeee_((((_)))) is case insensitive. The month and weekday names can consist of any combination of upper and lower case letters. The process can request that the input date or time specification be in a specific language by setting the _LLLL_CCCC______TTTT_IIII_MMMM_EEEE category (see _ssss_eeee_tttt_llll_oooo_cccc_aaaa_llll_eeee_((((_))))). Leading 0's are not necessary for the descriptors that allow leading 0's. However, at most two digits are allowed for those descriptors, including leading 0's. Extra whitespace in either the template file or in _ssss_tttt_rrrr_iiii_nnnn_gggg is ignored. PPPPaaaaggggeeee 2222 ggggeeeettttddddaaaatttteeee((((3333CCCC)))) ggggeeeettttddddaaaatttteeee((((3333CCCC)))) The field descriptors _%%%%_cccc, _%%%%_xxxx, and _%%%%_XXXX will not be supported if they include unsupported field descriptors. The following rules apply for converting the input specification into the internal format: If _%%%%_ZZZZ is being scanned, then _gggg_eeee_tttt_dddd_aaaa_tttt_eeee_((((_)))) initialises the broken-down time to be the current time in the scanned time zone. Otherwise it initialises the broken-down time based on the current local time as if _llll_oooo_cccc_aaaa_llll_tttt_iiii_mmmm_eeee_((((_)))) had been called. If only the weekday is given, today is assumed if the given day is equal to the current day and next week if it is less. If only the month is given, the current month is assumed if the given month is equal to the current month and next year if it is less and no year is given (the first day of month is assumed if no day is given). If no hour, minute and second are given the current hour, minute and second are assumed, If no date is given, today is assumed if the given hour is greater than the current hour and tomorrow is assumed if it is less. If a field descriptor specification in the _DDDD_AAAA_TTTT_EEEE_MMMM_SSSS_KKKK file does not correspond to one of the field descriptors above, the behaviour is unspecified. RRRREEEETTTTUUUURRRRNNNN VVVVAAAALLLLUUUUEEEE Upon successful completion, _gggg_eeee_tttt_dddd_aaaa_tttt_eeee_((((_)))) returns a pointer to a _ssss_tttt_rrrr_uuuu_cccc_tttt _tttt_mmmm_.... Otherwise, it returns a null pointer and _gggg_eeee_tttt_dddd_aaaa_tttt_eeee______eeee_rrrr_rrrr is set to indicate the error. EEEERRRRRRRROOOORRRRSSSS The _gggg_eeee_tttt_dddd_aaaa_tttt_eeee_((((_)))) function will fail in the following cases, setting _gggg_eeee_tttt_dddd_aaaa_tttt_eeee______eeee_rrrr_rrrr to the value shown in the list below. Any changes to errno are unspecified. 1 The _DDDD_AAAA_TTTT_EEEE_MMMM_SSSS_KKKK environment variable is null or undefined. 2 The template file cannot be opened for reading. 3 Failed to get file status information. 4 The template file is not a regular file. 5 An I/O error is encountered while reading the template file. 6 Memory allocation failed (not enough memory available). PPPPaaaaggggeeee 3333 ggggeeeettttddddaaaatttteeee((((3333CCCC)))) ggggeeeettttddddaaaatttteeee((((3333CCCC)))) 7 There is no line in the template that matches the input. 8 Invalid input specification. For example, February 31; or a time is specified that can not be represented in a _tttt_iiii_mmmm_eeee______tttt (representing the time in seconds since 00:00:00 UTC, January 1, 1970). EEEEXXXXAAAAMMMMPPPPLLLLEEEE Example 1: The following example shows the possible contents of a template: %m %A %B %d, %Y, %H:%M:%S %A %B %m/%d/%y %I %p %d,%m,%Y %H:%M at %A the %dst of %B in %Y run job at %I %p,%B %dnd %A den %d. %B %Y %H.%M Uhr Example 2: The following are examples of valid input specifications for the template in Example 1: getdate("10/1/87 4 PM"); getdate("Friday"); getdate("Friday September 18, 1987, 10:30:30"); getdate("24,9,1986 10:30"); getdate("at monday the 1st of december in 1986"); getdate("run job at 3 PM, december 2nd"); If the _LLLL_CCCC______TTTT_IIII_MMMM_EEEE category is set to a German locale that includes _ffff_rrrr_eeee_iiii_tttt_aaaa_gggg as a weekday name and _oooo_kkkk_tttt_oooo_bbbb_eeee_rrrr as a month name, the following would be valid: PPPPaaaaggggeeee 4444 ggggeeeettttddddaaaatttteeee((((3333CCCC)))) ggggeeeettttddddaaaatttteeee((((3333CCCC)))) getdate("freitag den 10. oktober 1986 10.30 Uhr"); Example 3: The following examples shows how local date and time specification can be defined in the template. Invocation Line in Template getdate("11/27/86") %m/%d/%y getdate("27.11.86") %d.%m.%y getdate("86-11-27") %y-%m-%d getdate("Friday 12:00:00") %A %H:%M:%S Example 4: The following examples help to illustrate the above rules assuming that the current date is Mon Sep 22 12:19:47 EDT 1986 and the _LLLL_CCCC______TTTT_IIII_MMMM_EEEE category is set to the default _""""_CCCC_"""" locale. Input Line in Template Date Mon %a Mon Sep 22 12:19:47 EDT 1986 Sun %a Sun Sep 28 12:19:47 EDT 1986 Fri %a Fri Sep 26 12:19:47 EDT 1986 September %B Mon Sep 1 12:19:47 EDT 1986 January %B Thu Jan 1 12:19:47 EST 1987 December %B Mon Dec 1 12:19:47 EST 1986 Sep Mon %b %a Mon Sep 1 12:19:47 EDT 1986 Jan Fri %b %a Fri Jan 2 12:19:47 EST 1987 Dec Mon %b %a Mon Dec 1 12:19:47 EST 1986 Jan Wed 1989 %b %a %Y Wed Jan 4 12:19:47 EST 1989 Fri 9 %a %H Fri Sep 26 09:00:00 EDT 1986 Feb 10:30 %b %H:%S Sun Feb 1 10:00:30 EST 1987 10:30 %H:%M Tue Sep 23 10:30:00 EDT 1986 13:30 %H:%M Mon Sep 22 13:30:00 EDT 1986 AAAAPPPPPPPPLLLLIIIICCCCAAAATTTTIIIIOOOONNNN UUUUSSSSAAAAGGGGEEEE Although historical versions of _gggg_eeee_tttt_dddd_aaaa_tttt_eeee_((((_)))) did not require that _<<<<_tttt_iiii_mmmm_eeee_...._hhhh_>>>> declare the external variable _gggg_eeee_tttt_dddd_aaaa_tttt_eeee______eeee_rrrr_rrrr, this document does require it. The Open Group encourages applications to remove declarations of _gggg_eeee_tttt_dddd_aaaa_tttt_eeee______eeee_rrrr_rrrr and instead incorporate the declaration by including _<<<<_tttt_iiii_mmmm_eeee_...._hhhh_>>>>. SSSSEEEEEEEE AAAALLLLSSSSOOOO _cccc_tttt_iiii_mmmm_eeee_((((_)))), _cccc_tttt_yyyy_pppp_eeee_((((_)))), _llll_oooo_cccc_aaaa_llll_tttt_iiii_mmmm_eeee_((((_)))), _ssss_eeee_tttt_llll_oooo_cccc_aaaa_llll_eeee_((((_)))), _ssss_tttt_rrrr_ffff_tttt_iiii_mmmm_eeee_((((_)))), _tttt_iiii_mmmm_eeee_ssss_((((_)))), _<<<<_tttt_iiii_mmmm_eeee_...._hhhh_>>>> PPPPaaaaggggeeee 5555 
